
\section{User's guide to sj.sty}

The {\sl Stata Journal\/} is produced using \texttt{statapress.cls} and
\texttt{sj.sty}, a {\LaTeXe} document class and package, respectively, each
developed and maintained at StataCorp by the Stata Press staff.  These files
manage the look and feel of each article in the {\sl Stata Journal}.

\subsection{The title page}

Each insert must begin with title-generating commands.  For example,

\begin{stverbatim}
\begin{verbatim}
\inserttype[st0001]{article}
\author{short author list}{%
  First author\\First affiliation\\City, State/Country\\Email address
  \and
  Second author\\Second affiliation\\City, State/Country\\Email address
}
\title[short toc title]{Long title for first page of journal insert}
\sjSetDOI{!!}
\maketitle
\end{verbatim}
\end{stverbatim}

Here \verb+\inserttype+ identifies the tag (for example, st0001) associated
with the journal insert and the insert type (for example, article).  The default
\verb+\inserttype+ is ``notag'', possibly with a number appended.
\verb+\author+ identifies the short and long versions of the list of
authors (that is, J. M. Doe for the short title and John Michael Doe for the 
long).  The short author list is only the author initial(s) and last name, and
the long author list is the author initial(s) and last name, author
affiliation(s), and city and state or country (spelled out with accents
applied as necessary). An email address should be included for, at least, the
corresponding author. \verb+\title+ identifies the short (optional) and long (required)
versions of the title of the journal insert.  The optional argument to
\verb+\title+ is used as the even-numbered page header.  If the optional
argument to \verb+\title+ is not given, the long title is used.  The required
argument to \verb+\title+ is placed in the table of contents with the short
author list.  Titles should not have any font changes or {\TeX} macros in
them.  \verb+\sjSetDOI{!!}+ is filled in by Stata Press with a {\smrm DOI}.
\verb+\maketitle+ must be the last command of this sequence; it uses
the information given in the previous commands to generate the title for a new
journal insert.

\subsection{The abstract}

The abstract is generated using the \texttt{abstract} environment.  The
abstract states the purpose of the article and area of research.
Abstracts must be able to stand alone from the full-text article. For
this reason, fully cite references rather than merely supplying the
author and date. Also, avoid introduction of acronyms in the abstract.
The \verb+\keywords+ are also appended to the abstract.  Here is an
example abstract with keywords:

\begin{stverbatim}
\begin{verbatim}
\begin{abstract}
This is an example article.  You should change the \input{} line in
\texttt{main.tex} to point to your file.  If this is your first submission to
the {\sl Stata Journal}, please read the following ``getting started''
information.

\keywords{\inserttag, command name(s), keyword(s)}
\end{abstract}
\end{verbatim}
\end{stverbatim}

\verb+\inserttag+ will be replaced automatically with the tag
given in \verb+\inserttype+ (here st0001). The first keyword will be the
article tag (assigned by Stata Press); other keywords for indexing purposes
should be added by the author(s). Community-contributed command names should
be listed after the article tag. Plural terms and multiple concepts should be
avoided.

\subsection{Sectioning}

All sections are generated using the standard {\LaTeX} sectioning commands:\\
\verb+\section+, \verb+\subsection+, \dots.

Sections in articles are numbered.  If the optional short section title is
given, it will be put into bookmarks for the electronic version of the
journal; otherwise, the long section title is used.  Like article titles,
section titles should not have any font changes or {\TeX} macros in them.

\subsection{The bib option}

\textsc{Bib}{\TeX} is a program that formats citations and references
according to a bibliographic style.  The following two commands load the
bibliographic style file for the {\sl Stata Journal\/} (\texttt{sj.bst}) and
open the database of bibliographic entries (\texttt{sj.bib}):

\begin{stverbatim}
\begin{verbatim}
\bibliographystyle{sj}
\bibliography{sj}
\end{verbatim}
\end{stverbatim}

Here are some example citations:
%
\citet{akaike}, \citet*{benAkivaLerman}, \citet{dykePatterson},
\citet{greene03},
\citet*{kendallstuart}, \citet{hilbe93a}, \citet{hilbe94}, \citet{hilbe93b},
\citet{maddala83}, and \citet*{latexcompanion}.
%
They are generated by using
the \verb+\citet+ and \verb+\citet*+ commands from the \texttt{natbib}
package.  Here we test \verb+\citeb+ and \verb+\citebetal+:
%
\citeb{akaike}, \citeb{benAkivaLerman}, \citeb{dykePatterson},
\citeb{greene03}, \citeb{kendallstuart}, \citeb{hilbe93a}, \citeb{hilbe94},
\citeb{hilbe93b}, \citeb{maddala83}, and \citeb{latexcompanion}.
Sometimes using the \verb+\cite+ macros will result in an overfull line as
shown above.  The solution is to list the author names and the citation year
separately, for example,
\verb+Ben-Akiva and Lerman [\citeyear{benAkivaLerman}]+.

The \texttt{bib} option of \texttt{statapress.sty} indicates that citations
and references will be formatted using \textsc{Bib}{\TeX} and the
\texttt{natbib} package.  This option is the default (meaning that it need not
be supplied), but there is no harm in supplying it to the \texttt{statapress}
document class in the main {\LaTeX} driver file (for example,
\texttt{main.tex}).

\begin{stverbatim}
\begin{verbatim}
\documentclass[bib]{sj}
\end{verbatim}
\end{stverbatim}

\noindent
If you choose not to use \textsc{Bib}{\TeX}, you can use the \texttt{nobib}
option of \texttt{statapress.sty}.

\begin{stverbatim}
\begin{verbatim}
\documentclass[nobib]{statapress}
\end{verbatim}
\end{stverbatim}

\noindent
\textsc{Bib}{\TeX}{} and bibliographic styles are described in
\citet*{latexcompanion}.

\subsection{Author information}

The {\sl About the authors\/} section is generated by using the
\texttt{aboutauthors} environment.  There is also an \texttt{aboutauthor}
environment for journal inserts by one author.  For example,

\begin{stverbatim}
\begin{verbatim}
\begin{aboutauthor}

Text giving background about the author goes in here.

\end{aboutauthor}
\end{verbatim}
\end{stverbatim}

\endinput
